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Abstract 

We present a very fast implementation of the Butler-Portugal algorithm for index 
canonicalization with respect to permutation symmetries. It is called xPerm, and 
has been written as a combination of a Mathematica package and a C subroutine. 
The latter performs the most demanding parts of the computations and can be 
linked from any other program or computer algebra system. We demonstrate with 
tests and timings the effectively polynomial performance of the Butler-Portugal 
algorithm with respect to the number of indices, though we also show a case in 
which it is exponential. Our implementation handles generic tensorial expressions 
with several dozen indices in hundredths of a second, or one hundred indices in a few 
seconds, clearly outperforming all other current canonicalizers. The code has been 
already under intensive testing for several years and has been essential in recent 
investigations in large-scale tensor computer algebra. 
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Program summary 



Title of program: xPerm 
Catalogue identifier: 

Program obtainable from: (submitted to Computer Physics Communications) 
http : //metric . iem. csic . es/Martin-Garcia/xAct/ 

Reference in CPC to previous version: 

Catalogue identifier of previous version: 

Does the new version supersede the original program?: 

Computers: Any computer running C and/or Mathematica 

Operating systems under which the new version has been tested: Linux, Unix, Win- 
dows XP, MacOS 



Preprint submitted to Elsevier 



6 March 2008 



Programming language: C and Mathematica (version 5.0 or higher) 
Memory required to execute with typical data: 20 Mbyte 
No. of bits in a word: 64 or 32 
No. of processors used: 1 

No. of bytes in distributed program, including test data, etc.: 1.5 Mbyte 
Distribution format: Unencoded compressed tar file 

Nature of physical problem: Canonicalization of indexed expressions with respect to 
permutation symmetries. 

Method of solution: The Butler-Portugal algorithm. 

Restrictions on the complexity of the problem: Multiterm symmetries are not con- 
sidered. 

Typical running time: A few seconds with generic expressions of up to 100 indices. 



1 Introduction 

Tensor calculus is essential in those areas of Physics and Engineering using 
curved manifolds and other geometrical structures to model physical objects. 
In particular, even the space-time itself can be the object of study, as in 
General Relativity or other modern theories of gravity. Computations in this 
context frequently become difficult, typically due to two main sources of com- 
plexity: a high dimensionality d or working with a large number n of indices. 
This is because the size of coordinate expansions grows as n d and the prob- 
lem of symmetry handling grows as n\, respectively. In those cases the use of 
Tensor Computer Algebra (TCA in the following) can be of great help. TCA 
is not only, however, a way of checking or avoiding our hand computations; 
the use of efficient algorithms combined with moderate computer resources 
(mainly RAM memory) can widen up enormously the set of problems that we 
can attack and solve. For a general review on TCA see Ref. [1]. 

This article focuses on the treatment of symmetries of tensorial expressions 
under permutations of their indices. Though the basic tensors used in our 
computations normally do not have complicated symmetries, their arbitrary 
tensor products can be very complicated. Traditional methods, based on list- 
ing permutations, are exponential in nature with respect to the number of 
indices, both in the time and memory required to solve a problem. They be- 
come therefore rather slow when working with expressions of several dozens 
of indices. The Butler-Portugal [2] algorithm, based on well-known efficient 
methods of computational group theory, is effectively polynomial and per- 
forms much better, as we will show with explicit examples comparing with 
other systems. 

Here we present for the first time a new implementation of the Butler- Portugal 
algorithm. It has been written both as a Mathematica package for generic ma- 
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nipulation of large groups of permutations, and as a C subroutine specialized 
in the index canonicalization problem. We shall refer to these two parts of 
the code as xPerm-Math and xPerm-C respectively. This system is the com- 
putational core for a fully-hedged abstract tensor package named xTensorhj 
the same author, and both are part of the integrated framework xAct [3] for 
Tensor Computer Algebra. The properties and capabilities of xTensor will be 
reported elsewhere. 

Section 2 summarizes very briefly the theoretical background behind the use of 
computational group theory in the problem of index canonicalization. Sections 
3 and 4 present the code, giving some examples of use. Section 5 analyzes 
three nontrivial problems, showing the high efficiency and speed of the system. 
Section 6 contains our conclusions. 



2 The algorithms 

In this article a tensor, like T cBla nc , is any expression with a head symbol (T 
in this case) and a list of slots where we can place indices. The expression can 
then be represented as T [c,B, 1 , a, -1 , -1 , -c] , where we use a minus sign to 
denote covariant indices. We shall not be concerned here with the types of 
indices that can be used, but we shall assume the following: paired symbols 
(like c and -c above) represent a contraction, in the usual Einstein convention; 
integer indices do not follow the Einstein convention, and can be repeated (like 
-1 above). The motivation for this is using symbols to denote abstract indices 
and integers for components. 

Any index configuration can be sorted into a canonical order following several 
predefined priorities (for instance symbols before integers, lowercase before 
uppercase, free before dummy, contravariant before covariant, etc). Following 
[2], we represent that index configuration as the permutation which brings it 
to canonical order. For example, if we assume that the canonical order for our 
configuration C ={c ,B, 1 ,a,-l , -1 , -c} is C ={a,c,-c,B, 1,-1,-1} then C 
can be converted into C using the permutation g = (1, 2, 4)(3, 5, 6, 7), in 
disjoint cyclic notation; that is, at the first slot of C we find the second index 
of Co, at the second slot we find the fourth index, at the fourth slot we find 
the first index, etc. We follow the convention of applying permutations on the 
right: C = C ■ g. For example (13) • (132) = (12) and (132) • (13) = (23). 
In other words, s 9 = i means that the image of slot s under the permutation 
g is the index % in the canonical list. Experimentally we find that the choice 
of index priorities for the canonical configuration deeply affects the overall 
efficiency of the algorithm; having paired indices in consecutive slots of Co 
seems to be the best option. 
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A permutation- symmetry of a tensor is any rearrangement under which the 
tensor remains invariant or changes sign. This forces us to work with signed 
permutations, which belong to the extended group {1,-1} x S n , rather than 
the symmetric group of n indices alone. A signed permutation (cr, 7r) with 
a = ±1 and n G S n acts on a tensor T ai _ an producing cT 7r ( ai ...a„)- There are 
two types of permutation-symmetries: 

• Those which involve a permutation of the slots independently of which in- 
dices they have (let us call them slot-symmetries) . For the Riemann tensor 
examples are 

Rbacd Rabcdi Rcdab Rabcd- 

The slot-symmetries of a tensor form a permutation group, denoted by S, 
not Abelian in general. 

• Those which involve a permutation among the indices independently of 
which slots they are in (call them index- symmetries) . There are three pos- 
sible sources: 

• Exchange of dummies: R ab a b = R ba ba- 

■ "Metric swapping": R ab a b = R a ba b (or £ A a = —^a A for an antisymmetric 
metric, as in spinor theory). 

• Repeated indices can always be exchanged, as the component indices 1 in 

jj>lalb 

These three sources give rise to three respective groups De, Dm and Dr, 
not Abelian in general, but which commute with each other. The complete 
group of index-symmetries of a tensor is D = De • Dm • Dr. 

As shown in [4], every problem of index canonicalization can be reduced to 
the problem of canonicalization of the indices of single tensors: terms in a 
sum are treated independently and factors in a tensor product can be sorted 
into canonical order so that their indices can be considered to belong to a 
single tensor. That tensor will inherit the slot-symmetries of the factors in 
the product, but can have additional slot-symmetries coming from exchange 
of several instances of the same tensor. (At this point it is relevant whether 
the tensor product is commutative or not.) In the following we shall assume 
that we work with a single tensor T"... of arbitrary slot-symmetry group S 
and index-symmetry group D. 

A given configuration of indices g is equivalent to any other configuration 
s ■ g ■ d with s £ S and d G D. The set S ■ g ■ D of permutations is called a 
double coset, not a group in general, and the problem of canonicalization of 
a configuration g in the presence of symmetries S and D can be reduced to 
defining and finding a canonical representative for the corresponding double 
cosetPl. Such an algorithm was given by Butler [6] for generic groups S and D, 

1 As far as I know, this was first elaborated in Ref. [5] and implemented in Reduce. 
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making intensive use of the efficient group representation provided by a strong 
generating set [7]: Given a group G of permutations acting on a set Q of points, 
a subset B = {bi, b k } of points 6, G is said to be a base of G iff none of 
the permutations of G fixes all points in B. Then we say that a generating set 
A of G is strong with respect to B iff there is a generating set in A for each 
of the stabilizer subgroups Gi = {g G G, , bf = bj for j = This induces 

a hierarchy G = Go ^ G\ D ... D Gk = {id} which efficiently represents the 
group G. The key idea is that problems concerning permutations in G can be 
translated into equivalent problems for the cosets of the in G i ^ 1 . A strong 
generating set and its base can be obtained from a normal generating set using 
the Schreier-Sims algorithm [7]. 

Butler's algorithm [6] for a permutation g G G starts from respective strong 
generating sets (Bs, A#) and (B D ,A D ) of two subgroups S and D of G. The 
base B s is extended to be a base B of G and then sequentially the points of 
base Bd are changed in a way determined by g, so that in the end Bd = B p , 
uniquely identifying the canonical permutation p of the double coset S ■ g ■ D. 
Butler's algorithm has been adapted by Portugal and collaborators [2] to the 
case of index canonicalization for a generic group S and a group D of the 
form D = D E • D M , which simplifies the process because the properties of the 
strong generating set for such a D group are known in advance. In tensorial 
terms, the base Bs defines priorities among the slots, and then the algorithm 
sequentially decides which indices are placed at those slots. Zero is returned 
as soon as —g is shown to belong to the double coset S ■ g- D. From now on we 
shall refer to this algorithm as the Butler-Portugal algorithm. For full details 
and examples see Ref. [2], and the Canon [8] implementation in Maple by the 
same authors. 

Butler's algorithm uses internally the intersection algorithm and hence it has 
global exponential efficiency in the number of indices at hand. In practical 
generic applications, however, it is effectively polynomial because only in a 
very small subset of cases the exponential character is apparent. This will 
become clear in the examples shown in Sect. 5. 

In this article we perform two straightforward extensions to include the pos- 
sibility of working with indices of different types (usually indices on different 
vector spaces) and also with component indices, which introduce the possi- 
bility of being repeated. Note that both issues affect the D group, but not 
the S group. The key observation is that the De and Dm groups act only 
on abstract indices, while the Dr group acts only on component indices, and 
so their actions are disjoint. The construction of the strong generating set for 
D from those of the three groups is hence trivial. The same observation ap- 
plies for the groups of the indices of different types which, by definition, also 
have disjoint action. Minor modifications of the Butler- Portugal algorithm are 
required to handle the new Dr groups. 
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3 A Mathematica implementation 

The xPerm package contains a number of tools for efficient manipulation of 
large groups of permutations. It has been fine tuned to the problem of index 
canonicalization, but can be used in a more general context. It is, however, 
rather limited in comparison with general-purpose environments in Computa- 
tional Group Theory like MAGMA [9] or GAP [10]. 

The package is loaded using standard Mathematica notation: 

In[l] := «xAct'xPerm < 

Package xAct'xPerm' version 1.0.0, {2008, 3, 5} 

Copyright (C) 2003-2008 Jose M. Martin-Garcia, under GPL 



There are three sets of commands and algorithms in xPerm. First we have 
basic tools to manipulate permutations. To avoid problems with the choice of 
notations, and to compare their different efficiencies, four different notations 
have been implemented. The permutation taking the numbers {1,2,3,4,5,6} to 
{3,2,4,1,6,5} can be represented using either of these: 

Perm [{3, 2, 4, 1, 6, 5}] , rearrangement of numbered objects. 

Images [{4, 2, 1, 3, 6, 5}] , list of images. 

Cycles [{1, 4, 3}, {5, 6}] , in disjoint cyclic notation. 

Rules [l->4, 4->3, 3->l, 5->6, 6->5] , convenient in Mathematica. 

The function TranslatePerm changes among different notations. Other simple 
functions include PermDeg, InversePerm, PermSort, etc., with obvious mean- 
ings. Products of permutations are taken with Permute. Given a generating 
set of permutations, the associated group can be constructed using the Dimino 
algorithm. 

A second type of algorithms are those in charge of constructing and manipu- 
lating strong generating sets. We have encoded a larger number of the algo- 
rithms given in Ref. [7], which include a combination of tools to analyze how 
points move under the permutations (orbits and Schreier vectors) and how 
they do not move under them (stabilizers). Relevant commands are Orbit, 
SchreierOrbit, TraceSchreier, Stabilizer, and others. The main algo- 
rithm is SchreierSims, which constructs a strong generating set of a group 
G from any generating set of G. For example, the symmetry group S of the 
Riemann tensor can be described by the generating set 

In[2j := GS = GenSet [ -Cycles [{1,2}] , Cycles [{1 ,3} , {2 ,4}] ]; 
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The list {1,3} is a base for S, but GS is not strong with respect to it (there is 
no permutation of the stabilizer Si in GS). We construct a strong generating 
set using 

InfS] := SGS = SchreierSims [{} , GS] 

OutfSj = StrongGenSet[{l,3}, 

GenSet[-Cycles[{l, 2}], Cycles[{l, 3}, {2, 4}], -Cycles[{3, 4}]] ] 

which has added the missing permutation. The group is then decomposed 
into a hierarchy of subgroups which can be used to get any piece of informa- 
tion using the principles of inductive foundation and backtrack search (the 
Search command). In particular we can test membership in the group with 
PermMemberQ and compute its order with OrderOf Group: 

In[4] := OrderOf Group [ SGS ] 

Out [4] = 8 

The documentation of xPerm shows all examples in [7] concerning these algo- 
rithms, correcting the results of some of them. 

The final third set of implemented algorithms are those needed for index 
canonicalization, following [2] with the simple extensions mentioned before. 
There is RightCosetRepresentative, which gives the canonical representa- 
tive of the right coset S-g for any permutation g and any group S. This is used 
to canonicalize free indices first. Then there is DoubleCosetRepresentative, 
which does the same for the double coset S ■ g ■ D, canonicalizing the dummy 
and component indices, taking into account the slot-symmetries which do not 
move the slots with free indices. This two-step process is more efficient than 
using only the second one only. Finally the function CanonicalPerm is in 
charge of the combination of both algorithms and is the only function to be 
called when doing index canonicalization. Let us see an example: 

Consider the expression Rb ldl R c bac . A product of two Riemann tensors has 
the slot-symmetries described by 

In[5] := SGS = StrongGenSet [ {1,3,5,7}, GenSet [ 
-Cycles [{1,2}] , -Cycles [{3,4}] , -Cycles [{5,6}] , -Cycles [{7,8}] , 
Cycles[{l,3},{2,4}] , Cycles [{5,7} , {6,8}] , 
Cycles[{l,5},{2,6},{3,7},{4,8}] ] ] ; 

The first line of permutations encodes the four pair antisymmetries; the second 
line describes symmetry under exchange of pairs in each Riemann; the third 
line exchanges both Riemanns. The indices {a,d,b,-b, c, -c , 1 , 1}, already in 
canonical order have index-symmetries described with the notation: 

In[6] := Dsets={DummySet [M, {{3 , 4} , {5 , 6}} , 1] , RepeatedSet [{7 , 8}] } ; 
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where the DummySet expression contains all dummies of space M, which has a 
symmetric metric (switch 1). There could be several of those expressions, one 
for each vector space, and several RepeatedSet expressions, one per repeated 
index. Other indices in the canonical list are free: 

In[7j := frees = {1,2}; 
Our expression is represented by the permutation 

In[8] := perm = Cycles[{l,4,8,5,6,3,2,7}] ; 
Hence the expression can be canonicalized using 

In[9] := CanonicalPerm [ perm, 8,SGS, frees, Dsets] 

Out[9j = Cycles[{2,3,4,5},{6,7}] 

which corresponds to the expression R ab b c R dl c l . 

Canonicalization can be performed using pure Mathematica code (xPerm- 
Math) or linking to an external compiled executable (xPerm-C) through the 
MathLink protocol, which is faster. This is controlled with the options MathLink 
-> False or MathLink -> True of CanonicalPerm, respectively. 



4 The C code for the canonicalizer 

All algorithms required for index canonicalization have been recoded in 2400 
lines of C code to increase the speed the system. We use some features of the 
C99 standard and hence the code must be compiled with some modern C com- 
piler like the GNU gcc compiler for Linux, Unix or Mac, or its cygwin port 
to Windows. For those systems with no such compilers the pure Mathemat- 
ica code presented in the previous section is always available, with identical 
output, but slower. 

Permutations are now represented always as lists of images (this is the Images 
notation in the Mathematica code of xPerm). The sign of a permutation is 
encoded in an additional pair of points at the end of the permutation. For 
instance Images [{2,3,4,1}] will be encoded as the list {2,3,4,1,5,6} and 
-Images [{2,3,4, 1}] as {2,3,4,1,6,5}. The product of two permutations 
pi and p2, both of degree n, is efficiently performed with the function 

void product (int *pl, int *p2, int *p, int n) { 
while (n— ) *(p++) = * (p2-l+* (pl++) ) ; 

} 
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which stores the result in p. Similarly, the inverse ip of a permutation p of 
degree n is computed using 



void inverse (int *p, int *ip, int n) { 

while (n— ) * (ip-l+* (p+n) ) = n+1 ; 

} 



A generating set of m permutations of degree n is stored as a list of mxn inte- 
gers. Functions are provided to compute images of points under permutations, 
stable points, stabilizers, orbits, Schreier vectors and other basic constructions 
in theory of finite groups. 

The Schreier-Sims algorithm has also been encoded in C, for completeness, 
though in typical applications in tensor algebra we do not expect to find the 
problem of computing a complex strong generating set from a given set of 
permutations. That could happen, for example, if we wanted to canonicalize 
a tensor with 48 indices and Rubik's group as symmetry (a group of 4 • 10 19 
permutations). Providing the obvious set of six generators it takes 5 seconds 
in xPerm to compute a strong generating set for that group. As a second non- 
trivial example, a strong generating set for the smallest of the three Conway 
simple sporadic groups, represented with permutations acting on 276 points, 
is constructed in 2.5 seconds. (This is a group of order 5 ■ 10 11 .) 

Finally there is the canonicalizer function, called canonical_perm_ext. Pro- 
totypes and further explanations on the structure of this and other functions 
are given in Appendix A, to help linking from other codes. In Mathematica 
the link can be performed via the MathLink protocol, and a template (.tin) 
file is provided with the xPerm package for this purpose. 



5 Examples and timings 

Example 1: Given a general antisymmetric tensor F ab = —F ba it is simple to 
see that 



The slot-symmetry group S in this problem is generated by the inherited 
permutations —(1,2), —(3,4), — (n — l,n) and the tensor-exchange permu- 
tations (1,3)(2,4), (3,5)(4, 6), (n — 3,n — l)(n — 2,n), in disjoint cyclic 
notation. This is a strong generating set with respect to the base points 
{1, 3, . . . , n — 1}. By accident, the groups S and D coincide, though this does 




if n odd 



if n even 



(1) 
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not introduce any simplification in the problem. These are large groups, with 
orders 5 • 10 32 for n = 25 and 3 • 10 79 for n = 50. Figure 1 shows a compar- 
ison of timings of canonicalization for different systems with respect to the 
number n of antisymmetric tensors. All systems correctly find that expres- 
sion (1) is zero for odd n, and it is clear that xPerm and Canon, which use 
the Butler-Portugal algorithm, are far more efficient than those systems using 
more traditional methods. We see that xPerm-C can handle 100 indices within 
a few seconds. Note also that more sophisticated methods carry an overhead 
which makes them slower for very low n. 
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Fig. 1. Timings, in a logarithmic axis, for canonicalization of expression (1) with 
various tensor canonicalizers: MathTensor [11], TTC (Tools of Tensor Calculus) 
[12], Canon [8] and both the pure Mathematica and the C-based codes reported in 
this article. The exponential character of the traditional methods vs. the effectively 
polynomial character of the Butler-Portugal algorithm is apparent. 

Example 2: We canonicalize random Riemann monomials with all indices 
contracted. Figure 2 shows the results for products of up to 9 Riemanns in 
MathTensor [11] and products of up to 50 Riemanns with our C canonical- 
izer. The global structure coincides with that of Figure 1, and in particular 
we also see that 100 indices can be also manipulated in just a few seconds. It 
is interesting to comment on the different behaviour of the cases giving zero 
and those giving nonzero results. MathTensor has a special rule transforming 
contractions of type R a a bc info 0, and those trivial zeros are detected in mil- 
liseconds. However there are other nontrivial zeros, like R ab R a b c d, which take 
even more than a second. The systematic and general algorithm of xPerm does 
not distinguish between trivial and nontrivial zeros and detects both in the 
same way, with an efficiency which seems to grow as n 3 . The non-zero results 
show a large disperssion in timings, but the average seems to grow like n 5 , 
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confirming the result of a similar experiment in [2]. 



The canonicalization of Riemann monomials is essential in our recent con- 
struction of the Invar package for fast manipulation of Riemann invariants, 
both algebraic invariants [13] and differential invariants [14]. 



■a 
a 

o 



to 



1000 



100 



10 



0.1 



o.oi 



0.001 



1000 



Minute • * J • - 100 



4 



: ..i.jjiiiih il' • !: ' 



10 




•+ 



- 0.1 



0.01 



0.001 



10 



20 30 

number of Riemann tensors 



40 



50 



Fig. 2. Timings, in a logarithmic axis, for canonicalization of scalar products of n 
Riemann tensors. There are 20 points per value of n for MathTensor [11], separated 
in those cases giving zero (brown open circles) and those given nonzero result (purple 
crosses). The exponential blow up is clear and it is not possible to go beyond n = 9 
with lGbtyte RAM. There are also 20 points per value of n for the C canonicalizer 
of xPerm and we show results up to n = 50 (that is, 200 indices), though it is 
possible to go much beyond with that RAM memory. Dark blue circles represent 
cases with nonzero results and magenta filled circles are cases with zero result (for 
reference we display the curve t{n) = 15 n 3 /xs). 

Example 3: Let us now concentrate on Riemann invariants of degree n = 10, 
so that we work with 40 indices. Fig. 3 shows an histogram of canonicalization 
timings of one million random invariants, separating those cases giving zero 
from those giving nonzero results. It is clear that zeros are faster than nonzero 
results, because the Butler-Portugal algorithm gives as soon as —g is found 
in the S ■ g ■ D double coset. We also see several peaks, corresponding to cases 
of different complexity. All zero cases are found in less than 0.1s, while several 
cases take more than a second to canonicalize. 

We believe that the hardest Riemann invariants to canonicalize are those of 
the form 
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which require listing 2n x 2 n permutations internally in the Butler-Portugal 
algorithm (in particular in the ALPHA table, see [2]), which clearly renders the 
whole process exponential in n. Compare this with a mere 2n for expressions 
(1). Once the hard cases have been identified it is always possible to prepare 
the system in advance to detect them and switch to adapted algorithms. For 
example, in this case the antisymmetric pairs ab in dimension d can be replaced 
by a single index A in dimension d(d — l)/2 converting the problem into 
R x Ai R A2 a 3 ■ ■ ■ R An An with Rab symmetric. This new problem is now nearly 
identical in nature to our Example 1, and hence as efficient. 
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Fig. 3. Histogram of canonicalization timings of one million algebraic Riemann in- 
variants of degree 10 with our C canonicalizer. Zeros (red) are found faster than 
nonzero (blue) results. The former are all contained in the figure, but there are 4097 
nonzero cases taking more than 0.1 s, and actually six of those take between 1 and 
6 seconds. Note the origin of the timings axis at 0.03 s. This is roughly the time 
that the driving tensor system xTensor [3] takes to compute the S and D groups 
from the tensor expression. 



6 Conclusions 



We have presented xPerm, a free-software package for efficient manipulation of 
large permutation groups in Mathematica. Its main objective is index canon- 
icalization under permutation symmetries of tensorial expressions. For this, 
xPerm implements the Butler- Portugal algorithm, which is effectively polyno- 
mial in the number of indices, in contrast to the clear exponential behaviour of 
more traditional algorithms. As far as the author knows, xPerm is currently 
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the fastest index canonicalizer, and this has been demonstrated comparing 
timings in some nontrivial example computations with other tensor computer 
algebra systems. 

With a tool like this at hand, we can enormously extend the type of problems 
in differential geometry that we can attack and solve. There are already sev- 
eral examples of projects in General Relativity which have been possible only 
through the use of xPerm. To name a few: the analysis of the hyperbolicity 
properties of large families of formulations of the Einstein equations [15] used 
in Numerical Relativity; the construction of the dynamical evolution equations 
for the Bel tensor [16]; the computation of the polarization of gravitational 
radiation at the third post-Newtonian order [17]; or the construction of a large 
database of equations among the algebraic and differential invariants of the 
Riemann tensor [13,14]. 

Authors of other free- software packages are encouraged to link to the C code 
presented here to gain efficiency in the process of index canonicalization, with 
the only proviso that they must require their users to cite this publication any 
time the combination of packages is used. The standalone system cadabra [18] 
already has this code at its computational core. 

xPerm can be downloaded from the webpage 

http : //metric . iem . csic . es/Martin-Garcia/xAct/ 
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A Prototypes of C functions 

1) The Schreier-Sims algorithm: Given a generating set A of m elements for 
the group G C S n , return a strong generating set A' with respect to a base B 
for the group G: 
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void schreier_sims(int *base, int bl, int *GS, int m, int n, 

int *newbase, int *nbl, int **newGS, int *nm, int *num) ; 

with input 

base: list of the first points of the base, 

bl: length of the list base, 

GS: list containing the original generating set, 

m: number of permutations in GS, 

n: degree of the permutations, 

and output 

newbase: final list of points in the base, 

nbl: number of points in the base, 

newGS: strong generating set, 

nm: number of permutations in newGS, 

num: number of generators checked in the process. 

2) Order of a group: Given a strong generating set A with respect to a base 
B, return the order of the group G generated: 

long long int order_of _group(int *base, int bl, int *GS, int m, int n) ; 

with identical input to the previous function and obvious output. 

3) Membership in a group: Given a strong generating set A of G with respect 
to a base B find whether a given permutation g belongs to G. 

int perm_member (int *p, int *base, int bl, int *GS, int m, int n) ; 

with identical input plus 

p: permutation to be tested, 
and output 1 if the permutation p belongs to the group G or otherwise. 

4) Double coset canonicalization: Given a permutation g we return its canon- 
ical representative taking into account the information of the slot-symmetry 
group S and the free, dummy and repeated indices. 

void canonical_perm_ext (int *perm, int n, 

int SGSQ, int *base, int bl, int *GS, int m, 
int *freeps, int fl, 

int *vds, int vdsl, int *dummies, int dl, int *mQ, 
int *vrs, int vrsl, int *repes, int rl, 
int *cperm) ; 
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Input: 



perm: permutation to be canonicalized 

n: degree of all permutations in the computation 

SGSQ: 1 if GS is strong and otherwise 

base: base of the strong generating set of S 

bl: length of the list base 

GS: (strong) generating set of S 

m: number of permutations in GS 

frees: free indices in input 

f 1: length of the list frees 

vds: list of lengths of dummy-sets 

vdsl: length of list vds 

dummies: list with pairs of dummies 

dl: length of list dummies 

mQ: list of symmetries of metric (-1, 0, 1) 

vrs: list of lengths of repeated-sets 

vrsl: length of list vrs 

repes: list with repeated indices 

rl: length of list repes 

Output: 

cperm: canonical permutation 

For the example in Sect. 3 the input data would as follows. (Note the permu- 
tations degree n = 10: the two last points encode the permutation sign.) 

perm = {4,7,2,8,6,3,1,5,9,10} n = 10 
SGSQ = 1 

base = {1,3,5,7} bl = 4 

GS = {2,1,3,4,5,6,7,8,10,9, 1,2,4,3,5,6,7,8,10,9, 
1,2,3,4,6,5,7,8, 10,9, 1,2,3,4,5,6,8,7, 10,9, 
3, 4, 1,2, 5, 6, 7, 8, 9, 10, 1,2, 3, 4, 7, 8, 5, 6, 9, 10, 
5,6,7,8,1,2,3,4,9,10} m = 7 

frees = {1,2} fl = 2 

vds = {4} mQ = {1} vdsl = 1 

dummies = {3,4,5,6} dl = 4 

vrs = {2} vrsl = 1 

repes = {7,8} rl = 2 

The output would be 

cperm = {1,3,4,5,2,7,6,8,9,10} 
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